home *** CD-ROM | disk | FTP | other *** search
/ Best of Shareware / Best of PC Windows Shareware 1.0 - Wayzata Technology (7111) (1993).iso / mac / ZIPPED / DOS / UTILITY / SRCH33.ZIP / SRCH.DOC < prev    next >
Text File  |  1992-10-17  |  11KB  |  305 lines
  1. SRCH 3.3 - Fast pattern matcher (with not-so fast replacement)
  2. --------------------------------------------------------------
  3.  
  4. Quick Introduction
  5. ------------------
  6. Type SRCH with no arguments for a concise listing of options.
  7.  
  8.  
  9. Introduction
  10. ------------ 
  11. SRCH is a "grep-like" pattern matching program. (If you don't know
  12. what grep is, don't worry about it!)  In its simplest form, you
  13. provide a pattern, and SRCH searches all the specified files for that
  14. pattern, printing out any occurrences it finds.  For example,
  15.  
  16.     SRCH  chocolate  recipe.1  recipe.2  recipe.3
  17.  
  18. will search the three recipe files for the pattern "chocolate".
  19. Every line that contains "chocolate" will be printed out.
  20.  
  21. You can specify as many files as you want, up to the MS-DOS limit
  22. on the command line length.  You can also use wildcard characters.
  23. For example, to search all the recipe files, you could type:
  24.  
  25.     SRCH  chocolate  recipe.*
  26.  
  27. SRCH's main advantage over other pattern matching programs is its
  28. speed.  It is based on the Boyer-Moore algorithm, and can search
  29. faster than many other searching programs.  The primary limitation
  30. of SRCH is that it will not (yet) search for regular expressions
  31. (i.e., you cannot have wildcards in the pattern).
  32.  
  33. SRCH is fast enough, especially on a hard disk, that it can replace
  34. more elaborate tools (such as database and text retrieval programs)
  35. when all that is needed is the ability look up information.  Since
  36. it works on plain text files, SRCH is quite flexible.  You can use
  37. your favorite word or text processor to enter information.  You can
  38. keep all your information in one big file, or (as with the recipe
  39. example above) you may choose to keep each piece of information as
  40. a separate file.  This strategy works quite well for small to
  41. medium size databases.
  42.  
  43. SRCH's Unix cousin, grep, is used extensively in this fashion.
  44. This may be one of the reasons that it took so long for real
  45. databases to appear in the Unix world!  One important application
  46. used by programmers is locating function and variable definitions
  47. and references in a set of modules.  For example, to find all
  48. occurrences of function named "foobar" in a set of C files, you
  49. could type:
  50.  
  51.     SRCH  foobar  *.c *.h
  52.  
  53.  
  54. With the -d option (see below), you can search an entire disk,
  55. subdirectories and all.  This can be quite useful when you've
  56. misplaced some information.  For example,
  57.  
  58.     SRCH  -d  chocolate  \
  59.  
  60. will find all occurrences of "chocolate" in any file on the current disk.
  61.  
  62.  
  63. If Your Output Looks Strange
  64. ---------------------------- 
  65. SRCH assumes that you are using ANSI.SYS (or something similar) in
  66. your CONFIG.sys file.  SRCH takes advantage of this to highlight
  67. the matched patterns that are printed and to clear lines.  If you
  68. do not use an ANSI driver, then you will see some strange
  69. characters adjacent to matched pattern. To eliminate this, use the
  70. -h option:
  71.  
  72.     SRCH  -h  chocolate  recipe.*
  73.  
  74. If you are redirecting, capturing, or printing output, you will
  75. also probably want to use this option.
  76.  
  77.  
  78. Replacement
  79. -----------
  80. SRCH can also do pattern replacement.  While it cannot replace patterns
  81. anywhere near as fast as it can find them, it does a creditable job.
  82.  
  83. If you run the following command:
  84.  
  85.     SRCH  -r  chocolate  vanilla  recipe.*
  86.  
  87. SRCH will go through all your recipe files and replace the pattern
  88. "chocolate" with the pattern "vanilla".  Normally, SRCH will print
  89. out each line that contains "chocolate", and ask you if you want
  90. to make the replacement in this line.  You can answer:
  91.  
  92.     y    "yes, make this replacement"
  93.     n    "no, do not make this replacement"
  94.     Ctrl-y    "yes, and make any other replacements without asking"
  95.     Ctrl-n    "no, and do not make any more replacements"
  96.  
  97. You must type one of these four characters; any other input will be
  98. ignored.  If the pattern occurs more than once in a line, you will
  99. be asked about the replacement more than once.
  100.  
  101. If you know in advance that you do not want to be queried about each
  102. line, use the -i option to turn off interactive mode.  Even with the
  103. -i option, all matching lines are shown; to eliminate this output,
  104. just redirect the output to the NUL device:
  105.  
  106.     SRCH  -r  chocolate  vanilla  recipe.*  >nul
  107.  
  108. A word of caution: SRCH does not backup your file when it replaces
  109. it.  It is advisable to make a copy of your file before doing a
  110. replace, in case you change your mind about the replacement.  Note
  111. that if you interrupt the replacement (with Ctrl-C) before it is
  112. complete, NO changes will be made.  However, if you let it run to
  113. completion, your original file will be permanently changed.
  114.  
  115.  
  116. Searching Based on Filenames
  117. ----------------------------
  118.  
  119. Using file masks and recursive directory search (see discussion of
  120. the "-d" and "-m" options below), SRCH can be used to locate files
  121. based on their name, rather than on their contents.  
  122.  
  123. To find all recipe files on the C: drive:
  124.  
  125.     SRCH  -d  -m  recipe.*  ""  c:\
  126.  
  127. Every file is considered to match the empty pattern (""), so all
  128. files generated with the file mask option will be located.
  129.  
  130.  
  131. Other Options
  132. -------------
  133.  
  134. SRCH's options are similar to those for the Unix "fgrep" command.
  135.  
  136. Usage:    SRCH [options] <pattern> [replacement] [file-list]
  137.  
  138. If no files are specified, and SRCH is on the tail end of a pipe, then
  139. SRCH will read from the pipe (standard input).  The command:
  140.  
  141.     DIR | SRCH  recipe
  142.  
  143. will print out all filenames that contain the pattern "recipe".
  144.  
  145. If the pattern (or replacement) contains blanks, then it must be quoted:
  146.  
  147.     SRCH  "chocolate cake"  recipe.*
  148.  
  149. The options are as follows:
  150.  
  151. -b    Opens files in text mode, rather than the default binary
  152.     mode.  This causes SRCH to treat the Ctrl-Z character as
  153.     the end of file; it also causes the -n option to count
  154.     each CR/LF pair as a single character (instead of two).
  155.  
  156. -c    Only prints the number of lines that contained the pattern.
  157.     For example,
  158.  
  159.         SRCH  -c  chocolate  recipe.*
  160.  
  161.     will tell you how many times the pattern chocolate occurs in
  162.     all the recipe files.
  163.  
  164. -d    Recursively search any directories.
  165.     If one of the filenames is a directory, this option will make
  166.     SRCH move to that directory and search all the files in that
  167.     directory for the pattern.  If any one of those files is a
  168.     directory, then SRCH moves down again, etc.
  169.     For example,
  170.  
  171.         SRCH  -d  chocolate  \
  172.  
  173.     will search the entire disk for files containing "chocolate".
  174.  
  175. -e    Take the next argument as the pattern.  This is necessary
  176.     if you have a pattern that starts with '-', since anything
  177.     starting with that character is assumed to be an option.
  178.     For example,
  179.  
  180.         SRCH  -e  -e  srch.doc
  181.  
  182.     will search this documentation for the pattern "-e".
  183.  
  184. -f    Normally, SRCH pretends that there is no difference between
  185.     upper and lower case (this is called "case folding").  The
  186.     -f option turns case folding off, so that the case must
  187.     match exactly.
  188.  
  189. -h    SRCH normally highlights the matched pattern in the line.
  190.     The -h option can be used to control how the highlighting
  191.     is done.  Using -h alone turns off highlighting, which is
  192.     useful for running without an ANSI driver, or for printing
  193.     to files or a printer.
  194.  
  195.     On the other hand, if you have the ANSI driver but do not
  196.     like the way things are highlighted, you can use the -h
  197.     option to specify the ANSI attributes for the highlight.
  198.     On a monochrome monitor, the following command will use
  199.     blinking reverse video as a highlight:
  200.  
  201.         SRCH -h5;7 chocolate recipe.*
  202.  
  203. -i    Turn off interactive mode.  This controls two features:
  204.  
  205.     (1) Display the name of each file as it is being searched.
  206.     Interactive mode displays the name of each file as it is being
  207.     searched.  The display is overwritten, so only the last/current
  208.     name will appear.  If SRCH's output is redirected, this information
  209.     will still appear on the screen.  If you are not using an ANSI
  210.     driver, use the -h option to suppress the "clear to end of line"
  211.     control sequences (however, you will still notice some garbage
  212.     on the screen).
  213.  
  214.     (2) Query user about each replacement.  If replacement (-r)
  215.     is specified, interactive mode queries the user about each
  216.     replacement (see the discussion above on replacement).  With
  217.     interactive mode turned off, all replacements are done without
  218.     user intervention.
  219.  
  220. -l    Instead of listing all the occurrences of the pattern in each
  221.     file, just list the names of the files which contain the pattern.
  222.     This may speed up the search, since once the pattern is located
  223.     in a file, there is no need to search any further in that file.
  224.  
  225. -m <pat> Use specified file mask to filter out files.  Normally, SRCH 
  226.     searches the specified files; however, with the -d option,
  227.     SRCH also scans all file in subdirectories.  A file mask is
  228.     used to limit the search to files with specific names.  For
  229.     example:
  230.  
  231.         SRCH  -d  -m  "recipe.*"  chocolate  *.*
  232.  
  233.     would search only files named "recipe.*" in the current
  234.     directory and in subdirectories.  Multiple masks can be
  235.     specified:
  236.  
  237.         SRCH  -d  -m  "recipe.* menu.*"  chocolate  *.*
  238.  
  239.     Remember to quote the mask (as in the above examples);
  240.     otherwise, if the current directory contains any files which
  241.     match the mask, an error will occur.
  242.  
  243.     The file mask matching uses Unix-style (shell) matching,
  244.     rather than DOS style matching.  For example, patterns like
  245.     "*abc.*" can be used.  In addition, character classes are
  246.     supported.  For example, "*.[ab]" matches "*.a" and "*.b".
  247.     (Note that the Unix-style matching is currently supported
  248.     only for file masks, not for the filename arguments
  249.     themselves.)
  250.  
  251. -n    Print the address (byte number in file) of each match.
  252.     (Unfortunately, the Boyer-Moore algorithm used in SRCH makes
  253.     it difficult to obtain the line number.)
  254.  
  255. -r    Perform a replacement.  A second pattern is specified as the
  256.     replacement pattern; see the discussion above for more info.
  257.  
  258. -s    Print nothing at all.  This is to allow batch files to examine
  259.     the errorlevel without creating any output.  SRCH returns the
  260.     following values:
  261.  
  262.         0    a match was found
  263.         1    no matches were found
  264.         2    an error occurred (bad file, option error, etc.)
  265.  
  266.  
  267.  
  268. A Word from Our Sponsor
  269. -----------------------
  270. SRCH is distributed as shareware.  If you find this program useful,
  271. a $15 registration fee is requested.
  272.  
  273. SRCH is written in C; the current version is compiled with Microsoft
  274. C version 6.  SRCH also runs under Unix System V.
  275.  
  276. SRCH may be redistributed freely.  It may not be sold for any
  277. purpose without written permission from the author.  If shipping,
  278. handling, and/or tax is charged, the total sum may not exceed $5.
  279.  
  280. If you like SRCH, or have any suggestions, comments, questions
  281. about current/future versions, or (heaven forbid!)  bug reports,
  282. please let me know.  Thanks!
  283.  
  284.     Jeff Dean
  285.     710 Chimalus
  286.     Palo Alto, CA  94306
  287.     USA
  288.  
  289.  
  290. Revision History
  291. ----------------
  292.  
  293. 3.3
  294.     Fixed replacement bug (introduced in 3.1 when binary
  295.     file support was added).
  296.  
  297. 3.2
  298.     Added support for file masks (the -m option)
  299.  
  300. 3.1
  301.     Added support for binary files (and the -b option)
  302.  
  303. 3.0
  304.     Shareware release
  305.